@asd20/ui-next 2.30.0 → 2.31.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+# [2.31.0](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.30.1...ui-next-v2.31.0) (2026-10-08)
+
+
+### Bug Fixes
+
+* allow intentional handbook detail-link exclusions ([67475cc](https://github.com/academydistrict20/asd20-ui-next/commit/67475ccf3dd0f240746d5be421be21223b9bb4fa))
+
+
+### Features
+
+* add contextual publication heading renderer ([9b3aca9](https://github.com/academydistrict20/asd20-ui-next/commit/9b3aca9f440aeb8cb39c4586e772857e24e7abaf))
+* add opt-in document print layer ([541d4e6](https://github.com/academydistrict20/asd20-ui-next/commit/541d4e65db4b75a8ffff9c4df673bc42104e416a))
+* checkpoint authenticated PDF staging and accessibility acceptance ([4319b1e](https://github.com/academydistrict20/asd20-ui-next/commit/4319b1edf132191c0d7d4d22a179182c819848e0))
+
+## [2.30.1](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.30.0...ui-next-v2.30.1) (2026-10-06)
+
+
+### Bug Fixes
+
+* update styling on student records form ([3c9e73b](https://github.com/academydistrict20/asd20-ui-next/commit/3c9e73b669569aead47346fe52c5df432d1ecbf7))
+
 # [2.30.0](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.29.1...ui-next-v2.30.0) (2026-10-06)
 
 

package/README.md

@@ -149,6 +149,10 @@ and runs `npm run verify:release` before publishing.
 
 ## Change Guidance
 
+The [PDFService implementation overview](docs/projects/pdf-service/README.md)
+records the shared PDF publishing proposal, Azure findings, contextual heading
+requirements, affected repositories, and staged implementation work.
+
 Before changing this package, identify which public entry point is affected and
 which downstream repos consume it. Template, style/token, icon, input model, and
 helper changes are especially likely to require downstream website or app

package/components.js

@@ -25,6 +25,8 @@ export { default as Asd20Viewport } from './src/components/atoms/Asd20Viewport/i
 export { default as Asd20WidgetViewport } from './src/components/atoms/Asd20WidgetViewport/index.vue'
 
 // Molecules
+export { default as Asd20PrintHeader } from './src/components/molecules/Asd20PrintHeader/index.vue'
+export { default as Asd20PrintContents } from './src/components/molecules/Asd20PrintContents/index.vue'
 export { default as Asd20Accordion } from './src/components/molecules/Asd20Accordion/index.vue'
 export { default as Asd20ActionMenuItem } from './src/components/molecules/Asd20ActionMenuItem/index.vue'
 export { default as Asd20BlockSchedule } from './src/components/molecules/Asd20BlockSchedule/index.vue'

package/helpers.js

@@ -1,5 +1,12 @@
 export { default as arraySearch } from './src/helpers/arraySearch.js'
+export { buildPublicationIntroduction } from './src/helpers/publicationIntroduction.js'
+export { prepareDocumentPrint, printDocument, installDocumentPrintLifecycle } from './src/helpers/documentPrint.js'
 export { default as buildFileSearchUrl } from './src/helpers/buildFileSearchUrl.js'
+export {
+  buildPublicationHeadingModels,
+  buildRichBodyRenderModel,
+} from './src/components/atoms/Asd20RichBodyContent/messageDocumentRenderer.js'
+export { createPublicationHeadingPrefix } from './src/components/atoms/Asd20RichBodyContent/headingContext.js'
 export { getCookie, setCookie } from './src/helpers/cookieRecipe.js'
 export { default as expandEvents } from './src/helpers/expandEvents.js'
 export { default as formatEventTime } from './src/helpers/formatEventTime.js'
@@ -52,3 +59,4 @@ export { default as queryPages } from './src/helpers/queryPages.js'
 export { default as queryPeople } from './src/helpers/queryPeople.js'
 export { default as sendEmail } from './src/helpers/sendEmail.js'
 export { default as sortOrgsByLevel } from './src/helpers/sortOrgsByLevel.js'
+export { buildHandbookDocument, documentImageUrls } from './src/helpers/handbookDocument.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asd20/ui-next",
-  "version": "2.30.0",
+  "version": "2.31.0",
   "private": false,
   "description": "ASD20 UI component library for Vue 3.",
   "license": "MIT",
@@ -41,6 +41,7 @@
     "focus-trap": "^6.9.4",
     "js-cookie": "3.0.8",
     "lodash": "^4.17.23",
+    "parse5": "8.0.0",
     "swiper": "12.2.0"
   },
   "peerDependencies": {

package/src/components/atoms/Asd20Messaging/index.vue

@@ -59,12 +59,15 @@
         v-html="longDescription"
       />
       <div
-        v-if="bodyContent"
+        v-if="bodyContent || bodyJson"
         class="asd20-messaging__body-content"
       >
         <asd20-rich-body-content
           :body-content="bodyContent"
           :body-json="bodyJson"
+          :heading-level-offset="headingLevelOffset"
+          :heading-id-prefix="headingIdPrefix"
+          @headings-change="$emit('headings-change', $event)"
         />
       </div>
 
@@ -113,6 +116,8 @@ export default {
     images: { type: Array, default: () => [] },
     heading: { type: String, default: '' },
     headingTagName: { type: String, default: 'h2' },
+    headingLevelOffset: { type: Number, default: 0 },
+    headingIdPrefix: { type: String, default: '' },
     shortDescription: { type: String, default: '' },
     longDescription: { type: String, default: '' },
     bodyContent: { type: String, default: '' },

package/src/components/atoms/Asd20RichBodyContent/headingContext.js

@@ -0,0 +1,255 @@
+import { defaultTreeAdapter, parseFragment, serialize, serializeOuter } from 'parse5'
+
+const HTML_NAMESPACE = 'http://www.w3.org/1999/xhtml'
+const HEADING_TAGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6'])
+
+// Each publication provides a complete, immutable plan before descendants render.
+export const publicationHeadingPlanKey = Symbol('asd20-publication-heading-plan')
+export const contextualAccordionItemKey = Symbol('asd20-contextual-accordion-item')
+
+export function createPublicationHeadingPrefix(documentId, occurrenceId) {
+  const encode = value => Array.from(new TextEncoder().encode(String(value)),
+    byte => byte.toString(16).padStart(2, '0')).join('')
+  return `pub-${encode(documentId)}-topic-${encode(occurrenceId)}`
+}
+
+export function normalizeHeadingContext(context = {}) {
+  const supplied = context.levelOffset === undefined ? 0 : context.levelOffset
+  const valid = Number.isInteger(supplied) && supplied >= 0 && supplied <= 5
+  const idPrefix = typeof context.idPrefix === 'string' ? context.idPrefix : ''
+  return {
+    ...context,
+    levelOffset: valid ? supplied : 0,
+    idPrefix,
+    active: supplied !== 0 || Boolean(idPrefix),
+    invalidOffset: Boolean(context.invalidOffset) || !valid,
+  }
+}
+
+function textLabel(node) {
+  if (node.nodeName === '#text') return node.value
+  if (['script', 'style', 'template'].includes(node.tagName)) return ''
+  if (node.tagName === 'br') return ' '
+  return (node.childNodes || []).map(textLabel).join('')
+}
+
+function getAttribute(node, name) {
+  return node.attrs?.find(attr => attr.name === name)?.value || ''
+}
+
+function setAttribute(node, name, value) {
+  const existing = node.attrs.find(attr => attr.name === name)
+  if (existing) existing.value = value
+  else node.attrs.push({ name, value })
+}
+
+function fragmentTarget(href, documentUrl) {
+  let hash = href.startsWith('#') ? href : ''
+  if (!hash && documentUrl) {
+    try {
+      const base = new URL(documentUrl)
+      const url = new URL(href, base)
+      if (url.origin === base.origin && url.pathname === base.pathname &&
+        url.search === base.search) hash = url.hash
+    } catch (_error) { /* Ordinary links retain the existing URL policy. */ }
+  }
+  if (!hash || hash === '#') return null
+  try { return decodeURIComponent(hash.slice(1)) } catch (_error) { return hash.slice(1) }
+}
+
+export function createHeadingSession(inputContext = {}) {
+  const context = normalizeHeadingContext(inputContext)
+  const prefix = context.idPrefix || 'body'
+  const entries = []
+  const headings = []
+  const diagnostics = []
+  const references = []
+  const headingStack = []
+  const accordionHeadings = new Map()
+  const report = (code, sourceKey, detail = '') => {
+    if (!diagnostics.some(row => row.code === code && row.sourceKey === sourceKey && row.detail === detail)) {
+      diagnostics.push({ code, sourceKey, detail })
+    }
+  }
+  if (context.invalidOffset) report('invalid-heading-offset', prefix)
+  if (!context.idPrefix) report('heading-namespace-missing', prefix)
+  if (!context.idPlan) report('document-heading-plan-unavailable', prefix)
+
+  function anchor(sourcePath, sourceId, candidate, kind = 'anchor') {
+    const key = `${prefix}:${sourcePath}`
+    entries.push({ key, sourcePath, sourceId: sourceId || null, candidate, prefix, kind })
+    if (sourceId && /\s/.test(sourceId)) report('invalid-source-anchor', key, sourceId)
+    const planned = context.idPlan?.idsBySourceKey[key]
+    if (context.idPlan && !planned) report('heading-plan-mismatch', key)
+    return { key, id: planned || sourceId || candidate }
+  }
+
+  function heading({ authoredLevel, label, sourcePath, sourceId = null,
+    kind = 'detail', accordionItemId = null }) {
+    const { key, id } = anchor(sourcePath, sourceId,
+      `${prefix}-${sourcePath}`, 'heading')
+    const requestedLevel = authoredLevel + context.levelOffset
+    const renderedLevel = Math.min(6, requestedLevel)
+    const codes = []
+    const add = code => { codes.push(code); report(code, key) }
+    if (requestedLevel > 6) add('heading-overflow')
+    if (authoredLevel === 1 && context.levelOffset) add('authored-h1-in-composition')
+    const normalizedLabel = String(label || '').replace(/\s+/g, ' ').trim()
+    if (!normalizedLabel) add('empty-heading-label')
+    while (headingStack.length && headingStack.at(-1).requestedLevel >= requestedLevel) headingStack.pop()
+    let parent = headingStack.at(-1) || null
+    const accordionParent = accordionItemId ? accordionHeadings.get(accordionItemId) : null
+    if (kind === 'detail' && accordionParent && !parent?.accordionItemId) parent = accordionParent
+    if (kind === 'detail' && accordionParent && requestedLevel <= accordionParent.requestedLevel) {
+      add('accordion-body-level-conflict')
+    }
+    // The containing message/topic title is one level above detail H2.
+    const parentLevel = parent?.requestedLevel ?? (1 + context.levelOffset)
+    if (requestedLevel > parentLevel + 1) add('heading-level-gap')
+    const descriptor = {
+      key, id, sourceId, sourcePath, kind, label: normalizedLabel,
+      authoredLevel, requestedLevel, renderedLevel,
+      overflow: requestedLevel > 6,
+      parentHeadingId: parent?.id || null, accordionItemId, aliasIds: [], diagnostics: codes,
+    }
+    headings.push(descriptor)
+    headingStack.push(descriptor)
+    if (kind === 'accordion-item') accordionHeadings.set(accordionItemId, descriptor)
+    return descriptor
+  }
+
+  function scope(render) {
+    const previous = [...headingStack]
+    try { return render() } finally { headingStack.splice(0, headingStack.length, ...previous) }
+  }
+
+  function href(value, sourcePath) {
+    const target = fragmentTarget(value, context.documentUrl || context.idPlan?.documentUrl)
+    if (target === null) return value
+    const sourceKey = `${prefix}:${sourcePath}`
+    references.push({ target, prefix, sourceKey })
+    const mapped = context.idPlan?.fragmentsByTopic[prefix]?.[target]
+    return mapped ? `#${encodeURIComponent(mapped)}` : value
+  }
+
+  function html(value, fieldPath, renderPlaceholder = null, accordionItemId = null) {
+    const fragment = parseFragment(
+      defaultTreeAdapter.createElement('div', HTML_NAMESPACE, []), value,
+      { onParseError: error => report('legacy-html-parse-recovery', `${prefix}:${fieldPath}`, error.code) }
+    )
+    let headingOrdinal = 0
+    const replacements = new Map()
+    const walk = (node, path, depth) => {
+      if (node.namespaceURI !== HTML_NAMESPACE) {
+        (node.childNodes || []).forEach((child, index) => walk(child, `${path}-${index}`, depth + 1))
+        return
+      }
+      const sourceId = getAttribute(node, 'id')
+      if (HEADING_TAGS.has(node.tagName)) {
+        const descriptor = heading({ authoredLevel: Number(node.tagName[1]),
+          label: textLabel(node), sourcePath: `html-${fieldPath}-h-${headingOrdinal++}`,
+          sourceId: sourceId || null, accordionItemId })
+        node.tagName = `h${descriptor.renderedLevel}`
+        node.nodeName = node.tagName
+        setAttribute(node, 'id', descriptor.id)
+      } else if (sourceId) {
+        const allocated = anchor(`html-${fieldPath}-element-${path}-id`, sourceId,
+          `${prefix}-html-${fieldPath}-element-${path}`)
+        setAttribute(node, 'id', allocated.id)
+      }
+      const name = node.tagName === 'a' ? getAttribute(node, 'name') : ''
+      if (name) {
+        // Identical id/name attributes represent one browser target, not two.
+        const allocated = name === sourceId
+          ? { id: getAttribute(node, 'id') }
+          : anchor(`html-${fieldPath}-element-${path}-name`, name,
+            `${prefix}-html-${fieldPath}-element-${path}-name`)
+        setAttribute(node, 'name', allocated.id)
+      }
+      const link = node.tagName === 'a' ? getAttribute(node, 'href') : ''
+      if (link) setAttribute(node, 'href', href(link, `html-${fieldPath}-element-${path}-href`))
+      const blockType = getAttribute(node, 'data-cc-block')
+      if (blockType) {
+        const nonempty = (node.childNodes || []).some(child =>
+          child.nodeName !== '#text' || child.value.trim())
+        if (nonempty) report('nonempty-body-placeholder', `${prefix}:${fieldPath}-${path}`)
+        else if (depth === 0 && node.tagName === 'div' && renderPlaceholder) {
+          const block = renderPlaceholder(blockType, getAttribute(node, 'data-block-id'), path)
+          if (block) replacements.set(node, { ...block, rootId: getAttribute(node, 'id') })
+          else report('unresolved-body-placeholder', `${prefix}:${fieldPath}-${path}`)
+        } else report('nested-body-placeholder', `${prefix}:${fieldPath}-${path}`)
+      }
+      (node.childNodes || []).forEach((child, index) => walk(child, `${path}-${index}`, depth + 1))
+    }
+    fragment.childNodes.forEach((node, index) => walk(node, String(index), 0))
+    const nodes = []
+    let pendingHtml = ''
+    const flush = () => {
+      if (pendingHtml) nodes.push({ type: 'html', html: pendingHtml })
+      pendingHtml = ''
+    }
+    for (const node of fragment.childNodes) {
+      if (replacements.has(node)) { flush(); nodes.push(replacements.get(node)) }
+      else pendingHtml += serializeOuter(node)
+    }
+    flush()
+    return { html: serialize(fragment), nodes }
+  }
+
+  return { context, entries, headings, diagnostics, references, report, anchor, heading, href, html, scope }
+}
+
+export function buildHeadingIdPlan(sessions, reservedIds = []) {
+  const entries = sessions.flatMap(session => session.entries)
+  const sourceCounts = new Map()
+  const used = new Set(reservedIds)
+  for (const entry of entries) {
+    if (entry.sourceId) {
+      sourceCounts.set(entry.sourceId, (sourceCounts.get(entry.sourceId) || 0) + 1)
+      used.add(entry.sourceId)
+    }
+  }
+  const idsBySourceKey = Object.create(null)
+  const fragmentsByTopic = Object.create(null)
+  const diagnostics = []
+  const sourceTargets = new Map()
+  for (const entry of entries) {
+    const preserve = entry.sourceId && sourceCounts.get(entry.sourceId) === 1 && !reservedIds.includes(entry.sourceId)
+    let id = preserve ? entry.sourceId : entry.candidate
+    if (!preserve) {
+      const candidate = id
+      let suffix = 2
+      while (used.has(id)) id = `${candidate}--${suffix++}`
+    }
+    used.add(id)
+    idsBySourceKey[entry.key] = id
+    if (entry.sourceId) {
+      const local = fragmentsByTopic[entry.prefix] || (fragmentsByTopic[entry.prefix] = Object.create(null))
+      if (Object.hasOwn(local, entry.sourceId)) {
+        diagnostics.push({ code: 'ambiguous-anchor', sourceKey: entry.key, detail: entry.sourceId })
+      } else local[entry.sourceId] = id
+      const targets = sourceTargets.get(entry.sourceId) || []
+      targets.push(id)
+      sourceTargets.set(entry.sourceId, targets)
+    }
+  }
+  for (const session of sessions) {
+    const prefix = session.context.idPrefix || 'body'
+    const local = fragmentsByTopic[prefix] || (fragmentsByTopic[prefix] = Object.create(null))
+    for (const reference of session.references) {
+      if (Object.hasOwn(local, reference.target)) continue
+      const targets = sourceTargets.get(reference.target)
+      if (targets?.length === 1) local[reference.target] = targets[0]
+      else if (targets?.length) diagnostics.push({ code: 'ambiguous-anchor', sourceKey: reference.sourceKey, detail: reference.target })
+      else if (reservedIds.includes(reference.target)) local[reference.target] = reference.target
+      else diagnostics.push({ code: 'unresolved-anchor', sourceKey: reference.sourceKey, detail: reference.target })
+    }
+  }
+  for (const local of Object.values(fragmentsByTopic)) Object.freeze(local)
+  return Object.freeze({
+    documentUrl: sessions[0]?.context.documentUrl || '',
+    idsBySourceKey: Object.freeze(idsBySourceKey),
+    fragmentsByTopic: Object.freeze(fragmentsByTopic),
+    diagnostics: Object.freeze(diagnostics.map(row => Object.freeze(row))),
+  })
+}

package/src/components/atoms/Asd20RichBodyContent/index.vue

@@ -14,11 +14,15 @@
       />
       <asd20-body-accordion
         v-else-if="node.type === 'accordion'"
+        :id="node.rootId || undefined"
         :key="`accordion-${node.block.id}-${index}`"
         :items="node.block.items"
+        :heading-level-offset="headingLevelOffset"
+        :heading-id-prefix="headingIdPrefix"
       />
       <asd20-tableau-embed
         v-else-if="node.type === 'tableau'"
+        :id="node.rootId || undefined"
         :key="`tableau-${node.block.id}-${index}`"
         :src="node.block.src"
         :height="node.block.height"
@@ -45,17 +49,26 @@ import {
   buildRichBodyRenderModel,
   containsBodyBlockPlaceholder,
 } from './messageDocumentRenderer'
+import { publicationHeadingPlanKey } from './headingContext'
 
 export default {
   name: 'Asd20RichBodyContent',
 
   components: { Asd20BodyAccordion, Asd20TableauEmbed },
 
+  inject: {
+    publicationHeadingPlan: { from: publicationHeadingPlanKey, default: null },
+  },
+
   props: {
     bodyContent: { type: String, default: '' },
     bodyJson: { type: [String, Object], default: '' },
+    headingLevelOffset: { type: Number, default: 0 },
+    headingIdPrefix: { type: String, default: '' },
   },
 
+  emits: ['headings-change'],
+
   data: () => ({
     hasMounted: false,
   }),
@@ -65,9 +78,18 @@ export default {
       return buildRichBodyRenderModel({
         bodyContent: this.bodyContent,
         bodyJson: this.bodyJson,
+        headingContext: {
+          levelOffset: this.headingLevelOffset,
+          idPrefix: this.headingIdPrefix,
+          idPlan: this.publicationHeadingPlan?.(),
+        },
       })
     },
     renderNodes() {
+      if (this.renderModel.headingContextApplied) {
+        return !this.hasMounted && this.renderModel.status === 'legacy'
+          ? this.renderModel.initialNodes : this.renderModel.nodes
+      }
       const html = this.bodyContent || ''
       // Keep SSR and the initial client render on the same raw HTML markup,
       // then enhance block placeholders after hydration.
@@ -82,6 +104,15 @@ export default {
     },
   },
 
+  watch: {
+    renderModel: {
+      immediate: true,
+      handler(model) {
+        this.$emit('headings-change', { headings: model.headings, diagnostics: model.headingDiagnostics })
+      },
+    },
+  },
+
   mounted() {
     this.hasMounted = true
     this.applyListColumnExceptions()