@asd20/ui-next 2.32.1 → 2.33.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+# [2.33.0](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.32.2...ui-next-v2.33.0) (2026-10-20)
+
+
+### Features
+
+* breadcrumbs now reflect previous wayfinding page if applicable; otherwise use current heirarchy ([d48b8ac](https://github.com/academydistrict20/asd20-ui-next/commit/d48b8ac0057c5a73b3f358f250025be822e78ef1))
+
+## [2.32.2](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.32.1...ui-next-v2.32.2) (2026-10-14)
+
+
+### Bug Fixes
+
+* refine handbook template; fix interior handbook links; move ctas; move translation indicator ([89c8b63](https://github.com/academydistrict20/asd20-ui-next/commit/89c8b6308e81ac6a0005f0d0fc8dac0ec92ecf34))
+
 ## [2.32.1](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.32.0...ui-next-v2.32.1) (2026-10-12)
 
 

package/README.md

@@ -35,6 +35,27 @@ multi-repo contract, not as an app-local component folder.
 - Unit test runner: Vitest
 - Component development: Storybook 8 with its retained webpack 5 builder
 
+## Breadcrumb Navigation
+
+Website templates accept an optional `breadcrumbContext` page reference supplied
+by the website's client navigation tracker. A visitor arriving from a wayfinding
+page sees that section in the breadcrumb when the destination is one of its
+message detail links or related pages. The context can continue between related
+detail pages and is cleared when the visitor leaves that section.
+
+Context is stored with the browser history entry, so refresh and Back/Forward
+can restore the context of that visit. Native same-tab links can also carry a short-lived
+arrival record when the referring page confirms the transition. Direct visits,
+unknown origins, unavailable browser storage, and discarded history state fall
+back to existing breadcrumbs. Context is restored after hydration.
+
+Only the header links change. URLs, Related Pages, `parentPage`, dates,
+categories, and the existing announcement/story navigation retain their behavior.
+There is no per-page editor setting or additional breadcrumb data request.
+
+Rollout requires releasing this UI package, updating the website's UI dependency,
+and deploying the website integration. CommCenter and the database need no changes.
+
 ## Public Entry Points
 
 Supported import paths are defined in `package.json` and guarded by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asd20/ui-next",
-  "version": "2.32.1",
+  "version": "2.33.0",
   "private": false,
   "description": "ASD20 UI component library for Vue 3.",
   "license": "MIT",

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

@@ -1116,7 +1116,7 @@ export function buildRichBodyRenderModel(input = {}) {
 }
 
 // This prepass is deliberately independent of Vue instances and mounted topics.
-export function buildPublicationHeadingModels({ bodies = [], reservedIds = [], documentUrl, linkResolverFactory } = {}) {
+export function buildPublicationHeadingModels({ bodies = [], reservedIds = [], reservedIdsFactory, documentUrl, linkResolverFactory } = {}) {
   const prefixes = new Set()
   const prepared = bodies.map(body => {
     const prefix = body.headingIdPrefix
@@ -1134,7 +1134,9 @@ export function buildPublicationHeadingModels({ bodies = [], reservedIds = [], d
     render(session)
     return { context, render, session }
   })
-  const headingPlan = buildHeadingIdPlan(prepared.map(row => row.session), reservedIds)
+  const sourceIds = prepared.flatMap(row => row.session.entries.map(entry => entry.sourceId).filter(Boolean))
+  const headingPlan = buildHeadingIdPlan(prepared.map(row => row.session),
+    [...reservedIds, ...(reservedIdsFactory?.(sourceIds) || [])])
   const idPlan = linkResolverFactory
     ? Object.freeze({ ...headingPlan, linkResolver: linkResolverFactory(headingPlan) })
     : headingPlan

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

@@ -137,6 +137,7 @@
         class="asd20-template-handbook__index"
         aria-label="Handbook topics"
       >
+        <slot name="sidebar-status" />
         <button
           class="asd20-template-handbook__index-toggle"
           type="button"
@@ -234,15 +235,30 @@
           class="asd20-template-handbook__summary"
           v-html="topicSummary(entry.message)"
         />
+        <div
+          v-if="topicCallsToAction(entry.message).length"
+          class="asd20-template-handbook__calls-to-action"
+        >
+          <asd20-button
+            v-for="cta in topicCallsToAction(entry.message)"
+            :key="cta.label"
+            :label="cta.label"
+            :link="cta.url"
+            :data-asd20-handbook-link="cta.handbookTargetId || undefined"
+            bordered
+            transparent
+          />
+        </div>
         <hr
           v-if="topicSummary(entry.message)"
           class="asd20-template-handbook__summary-divider"
         />
         <asd20-messaging
-          v-bind="topicMessage(entry.message)"
+          v-bind="entry.message"
           heading=""
           short-description=""
           detail-link=""
+          :calls-to-action="[]"
           :heading-level-offset="1"
           :heading-id-prefix="entry.key"
         />
@@ -373,11 +389,11 @@ export default {
     topicSummary(message) {
       return this.handbookDocument.linkResolver.html(message.shortDescription || message.summary || '')
     },
-    topicMessage(message) {
-      return { ...message, callsToAction: this.handbookDocument.linkResolver.callsToAction(message.callsToAction) }
+    topicCallsToAction(message) {
+      return this.handbookDocument.linkResolver.callsToAction(message.callsToAction)
     },
     entryForFragment(id) {
-      return this.topicEntries.find(entry => entry.titleId === id ||
+      return this.topicEntries.find(entry => entry.titleId === id || entry.legacyTitleId === id ||
         Object.entries(this.publicationHeadings.idPlan.idsBySourceKey).some(([key, target]) => key.startsWith(entry.key + ':') && target === id))
     },
     onFragmentChange() {
@@ -388,6 +404,10 @@ export default {
       try { id = decodeURIComponent(String(fragment || '').replace(/^#/, '')) } catch { return false }
       const entry = this.entryForFragment(id)
       if (!entry) return false
+      if (id === entry.legacyTitleId) {
+        id = entry.titleId
+        window.history.replaceState(window.history.state, '', `#${encodeURIComponent(id)}`)
+      }
       const epoch = ++this.fragmentEpoch
       this.selectedMessageId = entry.key
       this.expandedTopicId = entry.key
@@ -529,7 +549,13 @@ export default {
     margin: 0 0 space(1);
     border: 0;
     border-top: 1px solid currentColor;
-    opacity: 0.25;
+  }
+
+  &__calls-to-action {
+    display: flex;
+    flex-wrap: wrap;
+    gap: space(0.25);
+    margin-bottom: space(1);
   }
 
   &__index ol {

package/src/helpers/breadcrumbLinks.js

@@ -0,0 +1,42 @@
+function localPath(value) {
+  if (typeof value !== 'string' || !value.startsWith('/') ||
+    value.startsWith('//') || /[\\\s]/.test(value)) return null
+  try {
+    return new URL(value, 'https://breadcrumb.local').pathname.replace(/\/+$/, '') || '/'
+  } catch { return null }
+}
+
+function isBreadcrumbContext(page, { id, path, organization }) {
+  const parentPath = localPath(page?.path?.path)
+  return Boolean(parentPath && typeof (page.name || page.title) === 'string' && (page.name || page.title) &&
+    (!id || page.id !== id) && (!path || parentPath !== localPath(path)) &&
+    (!page.status || page.status === 'Published') &&
+    (!organization?.id || !page.ownerOrganizationId ||
+      organization.id === page.ownerOrganizationId))
+}
+
+function textLabel(value) {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+// Visit-specific context affects only the links displayed in the page header.
+export function buildBreadcrumbLinks({
+  breadcrumbContext,
+  parentPage,
+  id,
+  path,
+  organization,
+} = {}) {
+  const parent = isBreadcrumbContext(breadcrumbContext, { id, path, organization })
+    ? breadcrumbContext
+    : parentPage
+  if (!parent?.path?.path) return []
+
+  const links = parent.path.path === '/' ? [] : [{ url: '/', label: 'Home' }]
+  const label = parent.name || parent.title
+  links.push({
+    url: parent.path.path,
+    label: parent === breadcrumbContext ? textLabel(label) : label,
+  })
+  return links
+}

package/src/helpers/handbookDocument.js

@@ -4,6 +4,15 @@ import { createPublicationHeadingPrefix } from '../components/atoms/Asd20RichBod
 import { parseFragment } from 'parse5'
 import { createHandbookLinkResolver } from './handbookLinks'
 
+function topicSlug(message) {
+  // CMS slugs survive translation; remove their publishing-date suffix.
+  const label = message.slug
+    ? String(message.slug).replace(/-\d{4}-\d{2}-\d{2}$/, '')
+    : message.heading || message.title || 'topic'
+  return String(label).normalize('NFKD').replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'topic'
+}
+
 export function documentImageUrls(html, baseUrl) {
   const urls = new Set()
   const walk = node => {
@@ -26,15 +35,33 @@ export function buildHandbookDocument({ messages = [], metaDescription = '', doc
     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` }
+    return { message, key, legacyTitleId: `${key}-title`, subtopicsId: `${key}-subtopics` }
   })
+  const fixedIds = ['main', 'handbook-content', 'handbook-topics', ...reservedIds,
+    ...entries.flatMap(entry => [entry.legacyTitleId, entry.subtopicsId])]
+  const slugs = entries.map(entry => topicSlug(entry.message))
+  const candidates = new Set(slugs)
   const coverKey = createPublicationHeadingPrefix(documentId, 'cover')
   const bodies = entries.map(entry => ({ bodyContent: entry.message.bodyContent, bodyJson: entry.message.bodyJson, headingLevelOffset: 1, headingIdPrefix: entry.key }))
   if (includeIntroductionBody) bodies.push({ bodyContent: messages[0]?.bodyContent, bodyJson: messages[0]?.bodyJson, headingIdPrefix: coverKey })
   const headingModels = buildPublicationHeadingModels({
     documentUrl,
     bodies,
-    reservedIds: ['main', 'handbook-content', 'handbook-topics', ...reservedIds, ...entries.flatMap(entry => [entry.titleId, entry.subtopicsId])],
+    reservedIds: fixedIds,
+    reservedIdsFactory: sourceIds => {
+      // Keep authored section bookmarks intact when a title has the same slug.
+      const used = new Set([...fixedIds, ...sourceIds])
+      entries.forEach((entry, index) => {
+        const slug = slugs[index]
+        let id = slug, suffix = 2
+        while (used.has(id)) {
+          do { id = `${slug}-${suffix++}` } while (candidates.has(id))
+        }
+        used.add(id)
+        entry.titleId = id
+      })
+      return entries.map(entry => entry.titleId)
+    },
     linkResolverFactory: idPlan => createHandbookLinkResolver(entries, documentUrl, idPlan),
   })
   const introduction = buildPublicationIntroduction(messages[0], metaDescription)

package/src/helpers/handbookLinks.js

@@ -20,11 +20,11 @@ function canonicalLinks(message) {
   const detail = links.find(link => link?.type === 'Detail Link')
   // Match the website mapper's single selected Detail Link. The same field is
   // retained in the PDF source, keeping online/PDF behavior identical.
-  return [message.detailLink || detail?.url].filter(Boolean)
+  return [message.detailLink || detail?.url, ...(Array.isArray(message.contentPageUrls) ? message.contentPageUrls : [])].filter(Boolean)
 }
 
-// Only an included topic's declared detail-page URL identifies its canonical
-// destination. Duplicate/unknown destinations remain ordinary links.
+// Included topics are identified by declared detail links and CMS page/message
+// relationships. Duplicate/unknown destinations remain ordinary links.
 export function createHandbookLinkResolver(entries, documentUrl, idPlan) {
   const destinations = new Map()
   const handbookPage = destination(documentUrl, documentUrl)?.key
@@ -40,7 +40,16 @@ export function createHandbookLinkResolver(entries, documentUrl, idPlan) {
     }
   }
   function resolve(value) {
+    // Existing bookmarked topic fragments remain valid after adopting slugs.
+    let legacyFragment = ''
+    if (typeof value === 'string' && value.trim().startsWith('#')) legacyFragment = value.trim().slice(1)
     const url = destination(value, documentUrl)
+    if (url?.key === handbookPage) legacyFragment = url.hash.slice(1)
+    if (legacyFragment) {
+      try { legacyFragment = decodeURIComponent(legacyFragment) } catch { return null }
+      const entry = entries.find(entry => entry.legacyTitleId === legacyFragment)
+      if (entry) return { href: `#${encodeURIComponent(entry.titleId)}`, targetId: entry.titleId }
+    }
     const topics = url && destinations.get(url.key)
     if (topics?.size !== 1) return null
     const entry = [...topics][0]

package/src/helpers/mapPageQueryResultToPageTemplateProps.js

@@ -214,6 +214,7 @@ export default function mapPageQueryResultToPageTemplateProps(
       pageTypeId: pageData.pageTypeId,
       factoids: pageData.factoids,
       parentPage: pageData.parentPage,
+      breadcrumbContext: pageData.breadcrumbContext || null,
       relatedPages: pageData.relatedPages
         ? pageData.relatedPages.map(p => {
             const page = _get(p, 'page[0]')
@@ -272,6 +273,14 @@ export default function mapPageQueryResultToPageTemplateProps(
           callsToAction,
           detailLink: detailLink ? detailLink.link.url : '',
           detailLinkLabel: detailLink ? detailLink.link.title : '',
+          // Page paths are relative to the current website. A message can be
+          // shared across organizations, so only retain this site's pages.
+          contentPageUrls: (m.message.pages || [])
+            .map(row => row.page)
+            .filter(page => page?.status === 'Published' &&
+              page.ownerOrganizationId === pageData.ownerOrganizationId)
+            .map(page => page.path?.path)
+            .filter(path => typeof path === 'string' && path.startsWith('/') && !path.startsWith('//')),
         }
       }),
       people: pageData.people,

package/src/mixins/pageTemplateMixin.js

@@ -1,4 +1,5 @@
 import responsiveBreakpointMixin from './responsiveBreakpointMixin'
+import { buildBreadcrumbLinks } from '../helpers/breadcrumbLinks'
 
 function getMessageBodyHtml(message) {
   return (message && (message.bodyContent || message.bodyHtml)) || ''
@@ -81,6 +82,7 @@ export default {
     navigation: { type: Array, default: () => [] },
     actionItems: { type: Array, default: () => [] },
     parentPage: { type: Object, default: null },
+    breadcrumbContext: { type: Object, default: null },
     quickLinks: { type: Array, default: () => [] },
     socialLinks: { type: Array, default: () => [] },
     disclosureLinks: { type: Array, default: () => [] },
@@ -434,18 +436,13 @@ export default {
     },
 
     breadcrumbLinks() {
-      let links =
-        this.parentPage && this.parentPage.path.path !== '/'
-          ? [{ url: '/', label: 'Home' }]
-          : []
-      if (this.parentPage) {
-        links.push({
-          url: this.parentPage.path.path,
-          label: this.parentPage.name || this.parentPage.title,
-        })
-      }
-
-      return links
+      return buildBreadcrumbLinks({
+        breadcrumbContext: this.breadcrumbContext,
+        parentPage: this.parentPage,
+        id: this.id,
+        path: this.path,
+        organization: this.organization,
+      })
     },
 
     publishDateTime() {