Skip to content

Document archive

Past documents by category as lists of links, and a document page with download and viewer.

<div data-mount="archive"></div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/document-archive.css";
import { groupByCategory } from "capsomer/behavior/document-archive";

Usage

<div class="cap-archive">
  <section class="cap-archive-group">
    <div class="cap-archive-head">
      <h2 class="cap-archive-title" id="cat-programs">Programs</h2>
      <a class="cap-archive-more" href="/archive/programs">All 24 programs</a>
    </div>
    <ul class="cap-rows" data-cap="row-list" role="list" aria-labelledby="cat-programs">
      <li class="cap-row">
        <div class="cap-row-title"><a href="/archive/programs/fall-2026" aria-describedby="r1-detail">Fall 2026 program</a></div>
        <p class="cap-row-detail" id="r1-detail">Fall 2026 · Editor: Sam Lee</p>
        <span class="cap-row-meta">PDF, 2.4 MB</span>
      </li>
    </ul>
  </section>
</div>

<article class="cap-docview">
  <header class="cap-docview-head">
    [breadcrumb]
    <h1 class="cap-docview-title">Fall 2026 program</h1>
    <p class="cap-docview-sub">Fall 2026 · Editor: Sam Lee</p>
    <p class="cap-docview-download"><a href="/documents/fall-2026/download" class="cap-btn" data-variant="primary" download>Download the PDF</a> <span class="cap-link-meta">PDF, 2.4 MB</span></p>
  </header>
  <div class="cap-docview-body">[the app's PDF viewer]</div>
  <nav class="cap-docpager" aria-label="More in Programs">
    <a class="cap-docpager-link" rel="prev" href="/archive/programs/spring-2027"><span class="cap-docpager-dir">Previous</span> <span class="cap-docpager-title">Spring 2027 program</span></a>
    <a class="cap-docpager-link" rel="next" href="/archive/programs/spring-2026"><span class="cap-docpager-dir">Next</span> <span class="cap-docpager-title">Spring 2026 program</span></a>
  </nav>
</article>
<DocumentList docs={docs.map((d) => ({ key: d.slug, title: d.title, href: `${basePath}/${d.slug}`, detail: documentSubtitle(d) }))}
  label="Programs" empty="Documents are being added and will be listed here." renderLink={renderLink} />

<DocumentViewer title={doc.title} subtitle={documentSubtitle(doc)} before={<Breadcrumb items={trail} />}
  download={{ href: `/documents/${doc.slug}/download`, bytes: doc.size }}
  prev={prev && { title: prev.title, href: `${basePath}/${prev.slug}` }}
  next={next && { title: next.title, href: `${basePath}/${next.slug}` }}
  collection="Programs" renderLink={renderLink}>
  <PdfViewer url={`/documents/${doc.slug}/inline`} title={doc.title} />
</DocumentViewer>

Examples

One category's list

<div data-mount="list"></div>

A document's page: download, viewer, Previous and Next

<div data-mount="page"></div>

The first in its category: Next only, on the right

<div data-mount="first"></div>

The last in its category: Previous only

<div data-mount="last"></div>

Phone width

<div class="archive-narrow" data-mount="narrow"></div>

API reference

DocumentList

PropTypeRequiredDoes
docsreadonly ArchiveDoc[]Yes
labelledBystringThe list's name: the id of the heading over it (preferred), or a label.
labelstring
emptyReactNodeWhat an empty category says.
renderLink(props: ArchiveLinkProps) => ReactNode

DocumentArchive

PropTypeRequiredDoes
groupsreadonly ArchiveGroup[]Yes
level2 | 3The categories' heading level. Default 2.
renderLink(props: ArchiveLinkProps) => ReactNode

DocumentViewer

PropTypeRequiredDoes
titleReactNodeYes
subtitleReactNode"Fall 2026 · Editor: Sam Lee".
level1 | 2The page's heading level for the title. Default 1: the document is the page.
beforeReactNodeAbove the title: the page's breadcrumb.
download{ href: string; format?: string; bytes?: number | null; label?: string }
childrenReactNodeThe viewer itself (the app's PDF viewer), or a cover and summary.
prevPagerDoc | null
nextPagerDoc | null
collectionstringYesThe category's name, for the signs' name: "More in Programs".
prevLabelstringThe words a screen reader hears before a neighbor's title. Default "Previous" and "Next".
nextLabelstring
renderLink(props: ArchiveLinkProps) => ReactNode

Functions

FunctionSignatureDoes
groupByCategory<T>(docs: readonly T[], categoryOf: (item: T) => string, order?: readonly string[]): { category: string; docs: T[]; }[]The document archive's pure helper: documents by category (a document's neighbors in its category are series-nav's seriesPlace). No DOM. The app reads its documents and their order (by year, by season) from its own store; these keep the archive's list and its pages agreeing. Documents grouped by category, in the order given (categories not in order follow, in the order first met), each keeping the list's own order within it. Empty categories in order are kept, so a page can say a category has nothing yet.

Parts and data attributes

ClassIs
.cap-archivethe root
.cap-archive-emptya part
.cap-archive-groupa part
.cap-archive-heada part
.cap-archive-morea part
.cap-archive-titlea part
.cap-docviewits own class
.cap-docview-bodyits own class
.cap-docview-downloadits own class
.cap-docview-headits own class
.cap-docview-subits own class
.cap-docview-titleits own class

Accessibility

KeyDoes
Tab, Shift+TabMoves through the rows' links, or on a page through the download, the viewer's controls, Previous and Next
EnterFollows the focused link
j, kMove between the rows of a category's list (row-list)
  • Each category's list is named by its heading (aria-labelledby); a lone list takes label.
  • The pager is a nav named "More in <category>"; its links carry rel="prev" and rel="next".
  • Contrast: the subtitle, the empty line, the size and the direction words in --muted (4.5:1), the titles in --accent-text, the pager links' edge --line beside their text.
  • Forced colors: the pager links keep a LinkText edge.