@asd20/ui-next 2.31.3 → 2.31.5

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.31.5](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.31.4...ui-next-v2.31.5) (2026-10-09)
+
+
+### Bug Fixes
+
+* add specific cover sheet for each handbook ([6c1f423](https://github.com/academydistrict20/asd20-ui-next/commit/6c1f423c06be9caa2443eee0c6d74d975416cc5a))
+
+## [2.31.4](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.31.3...ui-next-v2.31.4) (2026-10-09)
+
+
+### Bug Fixes
+
+* remove handbook download statistics; add error modal; allow school named files for handbooks ([d81ded2](https://github.com/academydistrict20/asd20-ui-next/commit/d81ded2203f8e8591dabfb2c2dfa4c7bd2b2e7c5))
+
 ## [2.31.3](https://github.com/academydistrict20/asd20-ui-next/compare/ui-next-v2.31.2...ui-next-v2.31.3) (2026-10-09)
 
 

package/helpers.js

@@ -60,3 +60,4 @@ 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'
+export { handbookSchoolYear, isDistrictHandbook, handbookCoverTitle, handbookDownloadFilename } from './src/helpers/handbookPresentation.js'

package/package.json

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

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

@@ -3,19 +3,31 @@
     class="asd20-handbook-document"
     :data-asd20-document-root="documentId"
   >
-    <header>
-      <h1>{{ title }}</h1>
-      <div
-        v-if="document.introduction.lead"
-        class="asd20-page-header__lead"
-        v-html="document.introduction.lead"
+    <header class="asd20-handbook-document__cover">
+      <div class="asd20-handbook-document__cover-heading">
+        <h1>
+          <span class="asd20-handbook-document__organization">{{ coverTitle.organizationTitle }}</span>{{ ' ' }}
+          <span class="asd20-handbook-document__title">{{ coverTitle.handbookTitle }}</span>
+        </h1>
+        <img
+          v-if="organization.logoImageUrl"
+          class="asd20-handbook-document__logo"
+          :src="organization.logoImageUrl"
+          :alt="`${coverTitle.organizationTitle} logo`"
+        />
+      </div>
+      <div class="asd20-handbook-document__cover-body">
+        <asd20-messaging
+          :body-content="messages[0]?.bodyContent || ''"
+          :body-json="messages[0]?.bodyJson || ''"
+          :heading-id-prefix="document.coverKey"
+        />
+      </div>
+      <asd20-print-header
+        :canonical-url="documentUrl"
+        v-bind="printMetadata"
       />
     </header>
-    <asd20-print-header
-      :organization-title="organization.title || ''"
-      :canonical-url="documentUrl"
-      v-bind="printMetadata"
-    />
     <asd20-print-contents :headings="document.headings" />
     <main>
       <article
@@ -51,6 +63,7 @@ import Asd20Messaging from '../../atoms/Asd20Messaging'
 import Asd20PrintHeader from '../../molecules/Asd20PrintHeader'
 import Asd20PrintContents from '../../molecules/Asd20PrintContents'
 import { buildHandbookDocument } from '../../../helpers/handbookDocument'
+import { handbookCoverTitle } from '../../../helpers/handbookPresentation'
 import { publicationHeadingPlanKey } from '../../atoms/Asd20RichBodyContent/headingContext'
 
 export default {
@@ -65,9 +78,14 @@ export default {
     documentId: { type: String, required: true },
     documentUrl: { type: String, required: true },
     printMetadata: { type: Object, default: () => ({}) },
+    includeIntroductionBody: { type: Boolean, default: true },
+    schoolYear: { type: String, default: '' },
   },
   computed: {
     document() { return buildHandbookDocument(this.$props) },
+    coverTitle() {
+      return handbookCoverTitle(this.organization, this.document.introduction.heading || this.title, this.printMetadata.generatedAt || new Date().toISOString())
+    },
   },
 }
 </script>
@@ -81,5 +99,18 @@ export default {
   h3 { font-size: 13pt; }
   h4, h5, h6 { font-size: 11pt; }
   a { color: #111; }
+  &__cover { break-after: page; padding-top: 0.35in; }
+  &__cover-heading { display: flex; align-items: flex-start; justify-content: space-between; gap: 0.3in; }
+  &__cover h1 { flex: 1; font-size: 24pt; line-height: 1.3; margin: 0; color: #1e477d; }
+  &__organization, &__title { display: block; }
+  &__title { margin-top: 0.15in; font-size: 19pt; }
+  &__cover &__logo { width: 1.45in; max-width: 1.45in; max-height: 1.65in; object-fit: contain; }
+  &__cover-body { margin-top: 0.75in; }
+  &__cover-body .asd20-messaging { padding: 0; margin: 0; }
+  &__cover-body .asd20-messaging__body-content { font-size: 10pt; line-height: 1.5; }
+  &__cover-body p { margin: 0 0 0.18in; }
+  &__cover-body img { margin-top: 0.2in; }
+  &__cover .asd20-print-header { margin-top: 0.35in; font-size: 8pt; color: #555; }
+  &__cover .asd20-print-header p { margin: 0.05in 0; }
 }
 </style>

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

@@ -27,7 +27,7 @@
     />
 
     <asd20-page-header
-      :heading="title"
+      :heading="introduction.heading || title"
       :lead="handbookLead"
       :organization="organization"
       :organization-options="organizationOptions"

package/src/helpers/handbookDocument.js

@@ -18,7 +18,7 @@ export function documentImageUrls(html, baseUrl) {
 
 // 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 = [] } = {}) {
+export function buildHandbookDocument({ messages = [], metaDescription = '', documentId = 'handbook', documentUrl = '', reservedIds = [], includeIntroductionBody = false } = {}) {
   const counts = new Map()
   const entries = messages.slice(1).map((message, index) => {
     const identity = String(message.id ?? `position-${index}`)
@@ -27,18 +27,26 @@ export function buildHandbookDocument({ messages = [], metaDescription = '', doc
     const key = createPublicationHeadingPrefix(documentId, JSON.stringify([identity, ordinal]))
     return { message, key, titleId: `${key}-title`, subtopicsId: `${key}-subtopics` }
   })
+  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: entries.map(entry => ({ bodyContent: entry.message.bodyContent, bodyJson: entry.message.bodyJson, headingLevelOffset: 1, headingIdPrefix: entry.key })),
+    bodies,
     reservedIds: ['main', 'handbook-content', 'handbook-topics', ...reservedIds, ...entries.flatMap(entry => [entry.titleId, entry.subtopicsId])],
   })
   const introduction = buildPublicationIntroduction(messages[0], metaDescription)
+  const coverBody = includeIntroductionBody ? headingModels.models[entries.length] : null
   return {
     entries, introduction, headingModels,
+    coverKey, coverBody,
     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],
+    diagnostics: [...introduction.diagnostics, ...headingModels.headingDiagnostics,
+      ...(coverBody?.status === 'unsupported' ? [{ code: 'introduction-body-unsupported' }] : []),
+      ...(coverBody?.headings.some(heading => heading.renderedLevel === 1) ? [{ code: 'introduction-body-h1' }] : []),
+    ],
   }
 }

package/src/helpers/handbookPresentation.js

@@ -0,0 +1,66 @@
+// Shared website/PDF presentation rules. The renderer copy is generated by
+// scripts/sync-handbook-presentation.mjs.
+const districtId = '26eaf390-d8ab-11e9-a3a8-5de5bba4f125'
+
+function generationDateParts(generatedAt) {
+  if (!Number.isFinite(Date.parse(generatedAt)))
+    throw new Error('Invalid PDF generation date.')
+  return Object.fromEntries(
+    new Intl.DateTimeFormat('en-US', {
+      timeZone: 'America/Denver',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit'
+    })
+      .formatToParts(new Date(generatedAt))
+      .map((part) => [part.type, part.value])
+  )
+}
+
+export function handbookSchoolYear(generatedAt) {
+  const { year, month } = generationDateParts(generatedAt)
+  const start = Number(year) - (Number(month) < 7 ? 1 : 0)
+  return `${start}-${String(start + 1).slice(-2)}`
+}
+
+export function isDistrictHandbook(organization = {}) {
+  return (
+    organization.id === districtId ||
+    (!organization.id && organization.abbreviation === 'ASD20')
+  )
+}
+
+export function handbookCoverTitle(
+  organization = {},
+  firstMessageTitle = '',
+  generatedAt
+) {
+  const organizationTitle = isDistrictHandbook(organization)
+    ? 'Academy District 20'
+    : organization.title || organization.name || 'School'
+  const handbookTitle = isDistrictHandbook(organization)
+    ? firstMessageTitle || 'School Handbook'
+    : 'School Handbook'
+  return {
+    organizationTitle,
+    handbookTitle: `${handbookSchoolYear(generatedAt)} ${handbookTitle}`
+  }
+}
+
+export function handbookDownloadFilename(
+  organization = {},
+  generatedAt,
+  firstMessageTitle = ''
+) {
+  const safe = (value) =>
+    String(value || '')
+      .replace(/[^a-zA-Z0-9_. ()-]/g, '')
+      .trim()
+      .slice(0, 160)
+  const abbreviation = safe(organization.abbreviation).slice(0, 80)
+  const { year, month, day } = generationDateParts(generatedAt)
+  const title = isDistrictHandbook(organization)
+    ? `ASD20 ${safe(firstMessageTitle) || 'School Handbook'}`
+    : `${abbreviation ? abbreviation + ' ' : ''}School Handbook`
+  return `${title} - ${year}-${month}-${day}.pdf`
+}

package/src/helpers/publicationIntroduction.js

@@ -11,31 +11,16 @@ function nonemptyHtml(html) {
   return (parseFragment(String(html || '')).childNodes || []).some(visit)
 }
 
-function nonemptyJson(value) {
-  if (!value) return false
-  let doc = value
-  if (typeof value === 'string') {
-    try { doc = JSON.parse(value) } catch { return true }
-  }
-  if (doc?.version === 1 && Array.isArray(doc.blocks)) return doc.blocks.length > 0
-  const visit = node => {
-    if (node?.type === 'text') return Boolean(node.text?.trim())
-    if (!['doc', 'paragraph'].includes(node?.type)) return true
-    return (node.content || []).some(visit)
-  }
-  return visit(doc)
-}
-
 export function buildPublicationIntroduction(firstMessage, metaDescription = '') {
   const message = firstMessage || {}
   const lead = message.shortDescription || message.summary || metaDescription || ''
-  const excludedFields = ['heading', 'title', 'bodyContent', 'bodyJson', 'longDescription', 'images', 'callsToAction', 'detailLink', 'detailLinkLabel']
+  // First-message body/media belong to the PDF cover, never the online header.
+  const excludedFields = ['bodyContent', 'bodyJson', 'longDescription', 'images', 'callsToAction', 'detailLink', 'detailLinkLabel']
   const unmappedFields = []
-  for (const field of ['bodyContent', 'longDescription']) {
+  for (const field of ['longDescription']) {
     if (nonemptyHtml(message[field])) unmappedFields.push(field)
   }
-  if (nonemptyJson(message.bodyJson)) unmappedFields.push('bodyJson')
-  for (const field of ['images', 'callsToAction']) {
+  for (const field of ['callsToAction']) {
     if (message[field]?.length) unmappedFields.push(field)
   }
   // Detail links direct readers from wayfinding messages to detailed pages.
@@ -44,7 +29,7 @@ export function buildPublicationIntroduction(firstMessage, metaDescription = '')
   if (message.links?.some(item => (item?.link ?? item)?.type !== 'Detail Link')) unmappedFields.push('links')
   if (message.shortDescription && nonemptyHtml(message.summary) && message.summary !== lead) unmappedFields.push('summary')
   return {
-    messageId: message.id ?? null, mode: 'first-summary-lead', lead,
+    messageId: message.id ?? null, mode: 'first-message-header', heading: message.heading || message.title || '', lead,
     detailLinkPolicy: 'omit-wayfinding',
     leadSource: message.shortDescription || message.summary ? 'summary' : metaDescription ? 'metaDescription' : 'none',
     excludedFields: [...excludedFields, 'links', ...(message.shortDescription ? ['summary'] : [])],